/**
 * @file fault_data.h
 * @brief 故障事件数据模块头文件
 * @details 本文件定义了104协议中故障事件数据处理的相关函数。
 *          包括故障事件的初始化、验证、设置和获取等操作。
 *          提供完整的故障事件管理接口。
 * 
 * @author 电网104协议开发团队
 * @date 2024
 * @version 1.0
 * 
 * @note 所有函数都遵循104协议规范，确保严格的数据处理
 * @warning 数据转换失败时应返回相应的错误码，便于上层处理
 * 
 * @see protocol_types.h
 * @see error_codes.h
 */

#ifndef FAULT_DATA_H
#define FAULT_DATA_H

#include "protocol_types.h"
#include "error_codes.h"

#ifdef __cplusplus
extern "C" {
#endif

/* ==================== 故障事件数据类型定义 ==================== */

/**
 * @brief 故障事件信息结构 (M_FT_NA_1)
 */
typedef struct {
    u8 telemetry_count;                     /* 带时标遥信个数 */
    u8 telemetry_type;                      /* 遥信类型 */
    u16 telemetry_point_id;                 /* 故障遥信点号 */
    u8 telemetry_value;                     /* 遥信值 */
    cp56time2a_t fault_timestamp;          /* 故障时刻时标 */
    u8 analog_count;                        /* 遥测个数 */
    u8 analog_type;                         /* 遥测类型 */
    info_addr_t analog_address;             /* 遥测信息体地址 */
    float analog_value;                      /* 故障时刻数据归一化值或IEEE STD745短浮点数 */
} M_FT_NA_1_t;

/**
 * @brief 故障事件类型枚举
 */
typedef enum {
    FAULT_EVENT_TYPE_SHORT_CIRCUIT = 1,     /* 短路故障 */
    FAULT_EVENT_TYPE_GROUND_FAULT = 2,      /* 接地故障 */
    FAULT_EVENT_TYPE_OVERLOAD = 3,          /* 过载故障 */
    FAULT_EVENT_TYPE_UNDER_VOLTAGE = 4,     /* 欠压故障 */
    FAULT_EVENT_TYPE_OVER_VOLTAGE = 5,      /* 过压故障 */
    FAULT_EVENT_TYPE_FREQUENCY_ABNORMAL = 6, /* 频率异常故障 */
    FAULT_EVENT_TYPE_POWER_QUALITY = 7,     /* 电能质量故障 */
    FAULT_EVENT_TYPE_COMMUNICATION = 8,     /* 通信故障 */
    FAULT_EVENT_TYPE_EQUIPMENT = 9,         /* 设备故障 */
    FAULT_EVENT_TYPE_OTHER = 10,            /* 其他故障 */
    FAULT_TYPE_MAX = 11                     /* 最大故障类型 */
} fault_event_type_t;

/**
 * @brief 故障严重程度枚举
 */
typedef enum {
    FAULT_SEVERITY_MINOR = 1,               /* 轻微故障 */
    FAULT_SEVERITY_MODERATE = 2,            /* 中等故障 */
    FAULT_SEVERITY_MAJOR = 3,               /* 严重故障 */
    FAULT_SEVERITY_CRITICAL = 4,            /* 危急故障 */
    FAULT_LEVEL_MAX = 5                      /* 最大故障等级 */
} fault_severity_t;

/**
 * @brief 故障状态枚举
 */
typedef enum {
    FAULT_STATUS_ACTIVE = 1,                /* 故障激活 */
    FAULT_STATUS_CLEARED = 2,               /* 故障清除 */
    FAULT_STATUS_ACKNOWLEDGED = 3,          /* 故障确认 */
    FAULT_STATUS_IGNORED = 4,               /* 故障忽略 */
    FAULT_STATUS_MAX = 5                    /* 最大故障状态 */
} fault_status_t;

/**
 * @brief 故障事件数据
 */
typedef struct {
    u32 fault_id;                           /* 故障ID */
    fault_event_type_t fault_type;          /* 故障类型 */
    fault_severity_t severity;              /* 故障严重程度 */
    fault_status_t status;                  /* 故障状态 */
    cp56time2a_t fault_time;                /* 故障发生时间 */
    cp56time2a_t clear_time;                /* 故障清除时间 */
    u16 affected_circuit;                    /* 受影响回路 */
    u8 telemetry_count;                     /* 遥信个数 */
    u8 analog_count;                        /* 遥测个数 */
    u8* telemetry_data;                     /* 遥信数据 */
    float* analog_data;                     /* 遥测数据 */
    char description[128];                  /* 故障描述 */
} fault_event_data_t;

/**
 * @brief 故障事件数据组
 */
typedef struct {
    fault_event_data_t* events;             /* 故障事件数组 */
    u32 count;                              /* 事件个数 */
    u32 max_count;                          /* 最大事件个数 */
} fault_event_data_group_t;

/* ==================== 故障事件处理函数 ==================== */

/**
 * @brief 初始化故障事件数据
 * @details 初始化故障事件数据结构，设置默认值。
 *          用于创建新的故障事件数据。
 * 
 * @param fault_event 故障事件数据结构指针，不能为NULL
 * @return 协议错误码
 *         - PROTOCOL_SUCCESS: 初始化成功
 *         - PROTOCOL_ERROR_NULL_POINTER: 空指针错误
 * 
 * @note 初始化所有字段为默认值
 * @warning 输入指针不能为NULL
 * 
 * @see validate_fault_event
 * @see init_cp56time2a
 * @see init_qds
 */
protocol_error_t init_fault_event(fault_event_data_t* fault_event);

/**
 * @brief 验证故障事件数据
 * @details 验证故障事件数据的有效性。检查所有必要字段是否已正确设置，
 *          包括故障ID、类型、严重程度、状态等关键信息。
 * 
 * @param fault_event 故障事件数据结构指针，不能为NULL
 * @return 协议错误码
 *         - PROTOCOL_SUCCESS: 验证成功
 *         - PROTOCOL_ERROR_NULL_POINTER: 空指针错误
 *         - PROTOCOL_ERROR_INVALID_PARAM: 参数无效
 * 
 * @note 验证所有关键字段的有效性
 * @warning 输入指针不能为NULL
 * 
 * @see init_fault_event
 * @see validate_cp56time2a
 */
protocol_error_t validate_fault_event(const fault_event_data_t* fault_event);

/**
 * @brief 设置故障事件信息
 * @details 设置故障事件的基本信息，包括故障ID、类型、严重程度等。
 *          该函数用于更新故障事件的核心属性。
 * 
 * @param fault_event 故障事件数据结构指针，不能为NULL
 * @param fault_id 故障ID
 * @param fault_type 故障类型
 * @param severity 故障严重程度
 * @param affected_circuit 受影响回路
 * @return 协议错误码
 *         - PROTOCOL_SUCCESS: 设置成功
 *         - PROTOCOL_ERROR_NULL_POINTER: 空指针错误
 *         - PROTOCOL_ERROR_INVALID_PARAM: 参数无效
 * 
 * @note 设置故障事件的核心属性
 * @warning 输入指针不能为NULL
 * 
 * @see init_fault_event
 * @see validate_fault_event
 */
protocol_error_t set_fault_event_info(fault_event_data_t* fault_event, 
                                     u32 fault_id, fault_event_type_t fault_type,
                                     fault_severity_t severity, u16 affected_circuit);

/**
 * @brief 设置故障事件描述
 * @details 设置故障事件的描述信息。描述信息用于记录故障的详细情况，
 *          便于后续分析和处理。
 * 
 * @param fault_event 故障事件数据结构指针，不能为NULL
 * @param description 故障描述字符串，不能为NULL
 * @return 协议错误码
 *         - PROTOCOL_SUCCESS: 设置成功
 *         - PROTOCOL_ERROR_NULL_POINTER: 空指针错误
 *         - PROTOCOL_ERROR_INVALID_PARAM: 参数无效
 * 
 * @note 描述信息长度不能超过128字符
 * @warning 输入指针不能为NULL
 * 
 * @see init_fault_event
 * @see validate_fault_event
 */
protocol_error_t set_fault_event_description(fault_event_data_t* fault_event,
                                            const char* description);

/* ==================== 故障事件信息获取函数 ==================== */

/**
 * @brief 获取故障类型描述
 * @details 根据故障类型枚举值获取对应的中文描述字符串。
 *          用于将故障类型代码转换为可读的描述信息。
 * 
 * @param fault_type 故障类型枚举值
 * @return 故障类型描述字符串
 * 
 * @note 返回的字符串是静态常量，不需要释放内存
 * @note 未知故障类型返回"未知类型"
 * 
 * @see fault_event_type_t
 */
const char* get_fault_type_description(fault_event_type_t fault_type);

/**
 * @brief 获取故障严重程度描述
 * @details 根据故障严重程度枚举值获取对应的中文描述字符串。
 *          用于将故障严重程度代码转换为可读的描述信息。
 * 
 * @param severity 故障严重程度枚举值
 * @return 故障严重程度描述字符串
 * 
 * @note 返回的字符串是静态常量，不需要释放内存
 * @note 未知严重程度返回"未知等级"
 * 
 * @see fault_severity_t
 */
const char* get_fault_severity_description(fault_severity_t severity);

/**
 * @brief 获取故障状态描述
 * @details 根据故障状态枚举值获取对应的中文描述字符串。
 *          用于将故障状态代码转换为可读的描述信息。
 * 
 * @param status 故障状态枚举值
 * @return 故障状态描述字符串
 * 
 * @note 返回的字符串是静态常量，不需要释放内存
 * @note 未知状态返回"未知状态"
 * 
 * @see fault_status_t
 */
const char* get_fault_status_description(fault_status_t status);

#ifdef __cplusplus
}
#endif

#endif /* FAULT_DATA_H */
